Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

Utility Functions for Sequence Grabber Channel Components

Sequence grabber components provide several utility functions that your channel component can use. This section discusses those functions.

The SGAddMovieData function lets you add data and sample references to a movie.

Alternatively, you can use the SGWriteMovieData function to add data to a movie, and the SGAddFrameReference and SGGetNextFrameReference functions to keep track of sample references prior to creating a QuickTime movie from recorded data.

The SGSortDeviceList function allows you to sort the entries in the device list that you create for the sequence grabber when it calls your SGGetChannelDeviceList function (which is discussed on SGGetChannelDeviceList ).

The SGChangedSource function allows you to tell the sequence grabber that you have changed your source device.

The SGAddFrameReference and SGGetNextFrameReference functions take a pointer to a frame information structure as a parameter. The SeqGrabFrameInfo data type defines the format of a frame information structure.

struct SeqGrabFrameInfo {
    long            frameOffset;        /* offset to the sample */
    long            frameTime;          /* time that frame was captured */
    long            frameSize;          /* number of bytes in sample */
    SGChannel       frameChannel;       /* current connection to channel */
    long            frameRefCon;        /* reference constant for channel */
};
frameOffset
Specifies the offset to the sample. Your channel component obtains this value from the SGWriteMovieData function, described on SGWriteMovieData .
frameTime
Specifies the time at which your channel component captured the frame. This time value is relative to the data sequence. That is, this time is not represented in the context of any fixed time scale. Rather, your channel component must choose and use a time scale consistently for all sample references.
frameSize
Specifies the number of bytes in the sample described by the sample reference.
frameChannel
Identifies the current connection to your channel.
frameRefCon
Contains a reference constant for use by your channel component. You can use this value in any way that is appropriate for your channel component. For example, video channel components may use this value to store a reference to frame differencing information for a temporally compressed image sequence.

SGAddMovieData

The SGAddMovieData function allows your channel component to add data to a movie. This function combines the services provided by the SGWriteMovieData and SGAddFrameReference functions. Your channel component should not write data directly to the movie file--use this function instead.

pascal ComponentResult SGAddMovieData (SeqGrabComponent s,
                                         SGChannel c, Ptr p,
                                         long len,
                                         long *offset,
                                         long chRefCon,
                                         TimeValue time,
                                         short writeType);
s
Specifies the component instance that identifies the sequence grabber component that is using your channel. The sequence grabber provides this to you when it calls your SGInitChannel function (described on SGInitChannel ).
c
Identifies the connection to your channel.
p
Specifies the location of the data to be added to the movie.
len
Indicates the number of bytes of data to be added to the movie.
offset
Contains a pointer to a field that is to receive the offset to the new data in the movie. The sequence grabber component returns an offset that is correct in the context of the movie resource, even if the movie is currently stored in memory. That is, if the movie is in memory, the returned offset reflects the location that the data will have in a movie on a permanent storage device, such as a disk.
chRefCon
Contains your channel's reference constant.
time
Specifies the time at which your channel captured the frame. This time value is expressed in your channel's time scale.
writeType
Specifies the type of write operation. The following values are valid:
seqGrabWriteAppend
Append the new data to the end of the file. The sequence grabber sets the field referred to by the offset parameter to reflect the location at which it added the data.
seqGrabWriteReserve
Do not write any data to the output file. Instead, reserve space in the output file for the amount of data indicated by the len parameter. The sequence grabber sets the field referred to by the offset parameter to the location of the reserved space.
seqGrabWriteFill
Write the data into the location specified by the field referred to by the offset parameter. The sequence grabber sets that field to the location of the byte following the last byte it wrote.
This option is used to fill the space reserved previously when the writeType parameter was set to seqGrabWriteReserve .

RESULT CODES

File Manager errors Memory Manager errors

SGWriteMovieData

The SGWriteMovieData function allows your channel component to add data to a movie.

pascal ComponentResult SGWriteMovieData (SeqGrabComponent s,
                                          SGChannel c, Ptr p,
                                          long len, long *offset);
s
Contains a component instance that identifies the sequence grabber component that has connected to your channel component. The sequence grabber component provides this value to your channel component when it calls your SGInitChannel function (described on SGInitChannel ).
c
Identifies the connection to your channel.
p
Specifies the location of the data to be added to the movie.
len
Contains the number of bytes of data to be added to the movie.
offset
Contains a pointer to a long integer that is to receive the offset to the new data in the movie. The sequence grabber component returns an offset that is correct in the context of a movie resource, even if the movie data is currently stored in memory. That is, if the movie is in memory, the returned offset reflects the location that the data will have in a movie on a permanent storage device, such as a disk.

DESCRIPTION

The SGWriteMovieData function behaves differently depending upon when you call it. If you call it from your SGWriteSamples function, this function writes the movie data to the device that contains the recording operation's movie file. If you call this function at other times, it may write the movie data to a movie in memory, depending upon the recording options that are in effect.

RESULT CODES

File Manager errors Memory Manager errors

SGAddFrameReference

The SGAddFrameReference function allows your channel component to store sample references.

pascal ComponentResult SGAddFrameReference (SeqGrabComponent s,
                                          SeqGrabFrameInfoPtr frameInfo);
s
Contains a component instance that identifies the sequence grabber component that has connected to your channel component. The sequence grabber component provides this value to your channel component when it calls your SGInitChannel function (described on SGInitChannel ).
frameInfo
Contains a pointer to a frame information structure (defined by the SeqGrabFrameInfo data type). Your component must completely specify the reference by placing the appropriate information into the record referred to by this parameter. The format and content of the frame information structure are described on struct SeqGrabFrameInfo { long frameOffset; /* offset to the sample */ long frameTime; /* time that frame was captured */ long frameSize; /* number of bytes in sample */ SGChannel frameChannel; /* current connection to channel */ long frameRefCon; /* reference constant for channel */ }; .

DESCRIPTION

The sequence grabber component uses the information you provide to create a new sample reference in the movie that contains the captured data. You supply the information for the reference in a frame information structure.

RESULT CODES

Memory Manager errors

SEE ALSO

Your component can retrieve these references by calling the SGGetNextFrameReference function, which is described in the next section.

SGGetNextFrameReference

The SGGetNextFrameReference function allows your channel component to retrieve the sample references you stored by calling the SGAddMovieData or SGAddFrameReference function, described on SGAddMovieData and in the previous section, respectively.

pascal ComponentResult SGGetNextFrameReference
                                         (SeqGrabComponent s,
                                          SeqGrabFrameInfoPtr frameInfo,
                                          TimeValue *frameDuration,
                                          long *frameNumber);
s
Contains a component instance that identifies the sequence grabber component that has connected to your channel component. The sequence grabber component provides this value to your channel component when it calls your SGInitChannel function (described on SGInitChannel ).
frameInfo
Contains a pointer to a frame information structure (defined by the SeqGrabFrameInfo data type), which is described on struct SeqGrabFrameInfo { long frameOffset; /* offset to the sample */ long frameTime; /* time that frame was captured */ long frameSize; /* number of bytes in sample */ SGChannel frameChannel; /* current connection to channel */ long frameRefCon; /* reference constant for channel */ }; . Your component must identify itself to the sequence grabber component by setting the frameChannel field of this structure to the component instance that identifies the current connection to your channel. The sequence grabber component then returns information about the specified frame in the remaining fields of this structure.
frameDuration
Contains a pointer to a time value. The sequence grabber component calculates the duration of the specified frame and returns that duration in the structure referred to by this parameter. Note that the sequence grabber component cannot calculate the duration of the last frame in a sequence. In this case, the sequence grabber component sets the returned time value to -1.
frameNumber
Contains a pointer to a long integer. Your channel component specifies the frame number corresponding to the frame about which you want to retrieve information. Frames are numbered starting at 0. However, frame numbers need not start at 0, and they may not be sequential. Set the field referred to by the frameNumber parameter to -1 to retrieve information about the first frame in a movie.
The sequence grabber component returns the frame number of the movie's next frame into the field referred to by this parameter. You can use this value the next time you call SGGetNextFrameReference .

DESCRIPTION

The SGGetNextFrameReference function allows your channel component to process these references sequentially or randomly--you specify the relative frame for which you want to retrieve information. The sequence grabber component then retrieves and returns information for that frame. Typically, your channel component calls this function within its SGWriteSamples function (described on SGWriteSamples ).

RESULT CODE

paramErr

-50

Invalid parameter specified

SGSortDeviceList

The SGSortDeviceList function allows you to sort your device list alphabetically.

pascal ComponentResult SGSortDeviceList (SeqGrabComponent s,
                                         SGDeviceList list);
s
Specifies the component instance that identifies the sequence grabber component that is using your channel. The sequence grabber provides this to you when it calls your SGInitChannel function (described on SGInitChannel ).
list
Contains a pointer to a device list structure pointer.

DESCRIPTION

Your component constructs its device list whenever the sequence grabber calls your SGGetChannelDeviceList function (described on SGGetChannelDeviceList ). You may add entries to the device list in any order you like. Once you have built up your device list, you may use the SGSortDeviceList function to sort that list alphabetically, by device name. The sequence grabber correctly updates the selectedIndex field in the device list structure, as well.

The format and content of the device list structure are discussed earlier in this chapter, in "Working With Channel Devices," .

RESULT CODE

paramErr

-50

Invalid parameter value

SGChangedSource

The SGChangedSource function allows you to tell the sequence grabber that your component is now using a different device.

pascal ComponentResult SGChangedSource (SeqGrabComponent s,
                                         SGChannel c);
s
Specifies the component instance that identifies the sequence grabber component that is using your channel. The sequence grabber provides this to you when it calls your SGInitChannel function (described on SGInitChannel ).
c
Identifies the connection to your channel.

DESCRIPTION

Applications can instruct your channel to change its input device, for example, by calling the sequence grabber's SGSetChannelDevice function. The sequence grabber passes this request on to your channel component. Whenever you successfully change your input device, you should tell the sequence grabber by calling its SGChangedSource function. This allows the sequence grabber to update the information it keeps about your channel.

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next